When HyperCard 2.1 receives an Apple event, it sends an appleEvent message to the current card. That means that you can respond to Apple events with HyperTalk scripts. But before you try to write such scripts, there are some terms and conventions you should be familiar with.
The figure
Apple events are like a package full of raw materials that arrive at a factory. They have a return address on them -- in HyperTalk, a string of the form "Zone:Macintosh:Program". They have an explanation of what their contents are for -- the class and id, which together consititute a verb, directing the receiver what do to with the package. And of course there are the contents themselves -- the event parameters.
When you get one of these packages, you have to unpack it before you can make something out of the raw materials inside. But you can't just rip into the package willy-nilly. You have to ask for what you want, by name. "Give me the snod." "OK, now give me the lerd." You unpack the contents, one by one, and make out of them whatever you're directed to make by the class and id.
The catch is that the package doesn't come with a packing list. You're supposed to know what's in it -- you have a big book that tells you that whenever you get a package that you're supposed to make into a "wild plum", it's supposed to have a "bork", a "flam", and a "nitz" inside of it. So you unpack the bork, the flam, and the nitz, and then you make the wild plum out of them and send it back.
Apple event = package
class and id = terse directions for what to do with the package
parameters = contents of the package
keywords = names for each thing in the package
The lesson
In HyperTalk, when you handle the appleEvent message, you first look at the class and id, and they tell you what you're supposed to do with the event. If it's an event that you know how to handle, you already know what the parameters are -- you've agreed with the sender in advance on what's supposed to be in it, or it's a standard Apple event defined in the voluminous standard documentation. So you unpack the parameters with the "request" command, manipulate them, and send back what you made out of them with the "reply" command.
The script might look like this:
on appleEvent class,id,sender
if class & id is "wildplum" then
request ae data with keyword "bork"
if the result is not empty then -- probably "Not found"
reply error "Expected a bork but got none."
exit appleEvent
end if
put it into theBork
request ae data with keyword "flam"
.
.
get wildPlumMakingFunction(theBork,theFlam,theNitz) -- process it
reply it -- send back the reply
else pass appleEvent -- we don't recognize this event; pass it on
end appleEvent
Keywords
Think of a keyword for a piece of data in the package as its name -- it's the handle you need to pull it out of the package. Asking for a parameter by keyword is the same as asking for a piece of raw material by name.
Keywords are arbitrary. Whoever invents an Apple event makes them up, on the spot, out of the blue, to name the pieces of data that go along with the event. The standard Apple events that have already been defined, along with the keywords for their required and optional parameters, are described in the Apple Event Registry.
The direct object
Many Apple events arrive with just one piece of raw material in them, or one piece that's more important than the others. By convention, this piece is given the keyword "----" and is referred to in the Apple event documenation as "the direct object" or "the direct parameter". These are pretty ugly names, so in HyperTalk you can just call it the "data" and leave off the keyword specification -- HyperCard will know what you're talking about.
request appleEvent data
This is equivalent to the following statement.
request appleEvent data of keyword "----"
The direct object for the 'odoc' event is the list of documents to open.
The direct object for the 'dosc' event is the script to execute. And so on.
Event attributes
Apple events come along with more than just an address, a verb, and pieces of data. They also come with modifiers, or "attributes", which you can think of as "special handling instructions". The class, id, and sender are all attributes also, but HyperCard gives you these automatically as parameters to the appleEvent message. The timeout value, the transaction id, and the return id -- the identifier you put on the reply so that the sender knows, when his wild plum arrives, which package you made it out of -- are additional attributes. If you need to look at these, the "request" command will let you.
You can get the return id,
request appleEvent return id
request appleEvent data of keyword "rtid" -- same thing, only uglier
the timeout value,
request appleEvent data of keyword "timo"
the transaction id,
request appleEvent data of keyword "tran"
and whatever else you think you need, as long as you know its keyword. We have special forms of the request command for the class, id, sender, direct object, and return id -- for everything else, you have to tell HyperCard what you want by keyword.
request appleEvent class -- gives you the class attribute
request appleEvent id -- gives you the id attribute
request appleEvent sender -- gives you the sender attribute
request appleEvent data -- gives you the direct object parameter
request appleEvent return id -- gives you the return id attribute
